Next: , Up: Sequences Arrays Vectors   [Contents][Index]

6.1 Sequences

This section describes functions that accept any kind of sequence.

Function: sequencep object

This function returns t if object is a list, vector, string, bool-vector, or char-table, nil otherwise.

Function: length sequence

This function returns the number of elements in sequence. If sequence is a dotted list, a wrong-type-argument error is signaled. Circular lists may cause an infinite loop. For a char-table, the value returned is always one more than the maximum Emacs character code.

See Definition of safe-length, for the related function safe-length.

(length '(1 2 3))
    ⇒ 3

(length ())
    ⇒ 0

(length "foobar")
    ⇒ 6

(length [1 2 3])
    ⇒ 3

(length (make-bool-vector 5 nil))
    ⇒ 5

See also string-bytes, in Text Representations.

If you need to compute the width of a string on display, you should use string-width (see Size of Displayed Text), not length, since length only counts the number of characters, but does not account for the display width of each character.

Function: elt sequence index

This function returns the element of sequence indexed by index. Legitimate values of index are integers ranging from 0 up to one less than the length of sequence. If sequence is a list, out-of-range values behave as for nth. See Definition of nth. Otherwise, out-of-range values trigger an args-out-of-range error.

(elt [1 2 3 4] 2)
     ⇒ 3

(elt '(1 2 3 4) 2)
     ⇒ 3

;; We use string to show clearly which character elt returns.
(string (elt "1234" 2))
     ⇒ "3"

(elt [1 2 3 4] 4)
     error→ Args out of range: [1 2 3 4], 4

(elt [1 2 3 4] -1)
     error→ Args out of range: [1 2 3 4], -1

This function generalizes aref (see Array Functions) and nth (see Definition of nth).

Function: copy-sequence sequence

This function returns a copy of sequence. The copy is the same type of object as the original sequence, and it has the same elements in the same order.

Storing a new element into the copy does not affect the original sequence, and vice versa. However, the elements of the new sequence are not copies; they are identical (eq) to the elements of the original. Therefore, changes made within these elements, as found via the copied sequence, are also visible in the original sequence.

If the sequence is a string with text properties, the property list in the copy is itself a copy, not shared with the original’s property list. However, the actual values of the properties are shared. See Text Properties.

This function does not work for dotted lists. Trying to copy a circular list may cause an infinite loop.

See also append in Building Lists, concat in Creating Strings, and vconcat in Vector Functions, for other ways to copy sequences.

(setq bar '(1 2))
     ⇒ (1 2)

(setq x (vector 'foo bar))
     ⇒ [foo (1 2)]

(setq y (copy-sequence x))
     ⇒ [foo (1 2)]


        
(eq x y)
     ⇒ nil


        
(equal x y)
     ⇒ t


        
(eq (elt x 1) (elt y 1))
     ⇒ t


        

        
;; Replacing an element of one sequence.
(aset x 0 'quux)
x ⇒ [quux (1 2)]
y ⇒ [foo (1 2)]


        

        
;; Modifying the inside of a shared element.
(setcar (aref x 1) 69)
x ⇒ [quux (69 2)]
y ⇒ [foo (69 2)]


      

    

  


  

    
Function:
    reverse sequence


    

      
      
      
      

      
This function creates a new sequence whose elements are
      the elements of sequence, but in reverse order.
      The original argument sequence is not
      altered. Note that char-tables cannot be reversed.


      

        
(setq x '(1 2 3 4))
     ⇒ (1 2 3 4)


        
(reverse x)
     ⇒ (4 3 2 1)
x
     ⇒ (1 2 3 4)


        
(setq x [1 2 3 4])
     ⇒ [1 2 3 4]


        
(reverse x)
     ⇒ [4 3 2 1]
x
     ⇒ [1 2 3 4]


        
(setq x "xyzzy")
     ⇒ "xyzzy"


        
(reverse x)
     ⇒ "yzzyx"
x
     ⇒ "xyzzy"


      

    

  


  

    
Function:
    nreverse sequence


    

       
      

      
This function reverses the order of the elements of
      sequence. Unlike reverse the original
      sequence may be modified.


      
For example:


      

        
(setq x '(a b c))
     ⇒ (a b c)


        
x
     ⇒ (a b c)
(nreverse x)
     ⇒ (c b a)


        
;; The cons cell that was first is now last.
x
     ⇒ (a)


      


      
To avoid confusion, we usually store the result of
      nreverse back in the same variable which held
      the original list:


      

        
(setq x (nreverse x))


      


      
Here is the nreverse of our favorite example,
      (a b c), presented graphically:


      

        
Original list head:                       Reversed list:
 -------------        -------------        ------------
| car  | cdr  |      | car  | cdr  |      | car | cdr  |
|   a  |  nil |<--   |   b  |   o  |<--   |   c |   o  |
|      |      |   |  |      |   |  |   |  |     |   |  |
 -------------    |   --------- | -    |   -------- | -
                  |             |      |            |
                   -------------        ------------


      


      
For the vector, it is even simpler because you don’t
      need setq:


      

        
(setq x [1 2 3 4])
     ⇒ [1 2 3 4]
(nreverse x)
     ⇒ [4 3 2 1]
x
     ⇒ [4 3 2 1]


      


      
Note that unlike reverse, this function
      doesn’t work with strings. Although you can alter
      string data by using aset, it is strongly
      encouraged to treat strings as immutable.

    

  


  

    
Function:
    sort sequence predicate


    

      
      
      

      
This function sorts sequence stably. Note that
      this function doesn’t work for all sequences; it may be
      used only for lists and vectors. If sequence is a
      list, it is modified destructively. This functions returns
      the sorted sequence and compares elements using
      predicate. A stable sort is one in which elements
      with equal sort keys maintain their relative order before and
      after the sort. Stability is important when successive sorts
      are used to order elements according to different
      criteria.


      
The argument predicate must be a function that
      accepts two arguments. It is called with two elements of
      sequence. To get an increasing order sort, the
      predicate should return non-nil if
      the first element is “less” than the second, or
      nil if not.


      
The comparison function predicate must give
      reliable results for any given pair of arguments, at least
      within a single call to sort. It must be
      antisymmetric; that is, if a is less than
      b, b must not be less than
      a. It must be transitive—that is,
      if a is less than b, and b
      is less than c, then a must be less
      than c. If you use a comparison function which
      does not meet these requirements, the result of
      sort is unpredictable.


      
The destructive aspect of sort for lists is
      that it rearranges the cons cells forming sequence
      by changing CDRs. A nondestructive sort
      function would create new cons cells to store the elements in
      their sorted order. If you wish to make a sorted copy without
      destroying the original, copy it first with
      copy-sequence and then sort.


      
Sorting does not change the CARs of the
      cons cells in sequence; the cons cell that
      originally contained the element a in
      sequence still has a in its
      CAR after sorting, but it now appears in a
      different position in the list due to the change of
      CDRs. For example:


      

        
(setq nums '(1 3 2 6 5 4 0))
     ⇒ (1 3 2 6 5 4 0)


        
(sort nums '<)
     ⇒ (0 1 2 3 4 5 6)


        
nums
     ⇒ (1 2 3 4 5 6)


      


      
Warning: Note that the list in
      nums no longer contains 0; this is the same cons
      cell that it was before, but it is no longer the first one in
      the list. Don’t assume a variable that formerly held
      the argument now holds the entire sorted list! Instead, save
      the result of sort and use that. Most often we
      store the result back into the variable that held the
      original list:


      

        
(setq nums (sort nums '<))


      


      
For the better understanding of what stable sort is,
      consider the following vector example. After sorting, all
      items whose car is 8 are grouped at the
      beginning of vector, but their relative order is
      preserved. All items whose car is 9 are grouped
      at the end of vector, but their relative order
      is also preserved:


      

        
(setq
  vector
  (vector '(8 . "xxx") '(9 . "aaa") '(8 . "bbb") '(9 . "zzz")
          '(9 . "ppp") '(8 . "ttt") '(8 . "eee") '(9 . "fff")))
     ⇒ [(8 . "xxx") (9 . "aaa") (8 . "bbb") (9 . "zzz")
         (9 . "ppp") (8 . "ttt") (8 . "eee") (9 . "fff")]


        
(sort vector (lambda (x y) (< (car x) (car y))))
     ⇒ [(8 . "xxx") (8 . "bbb") (8 . "ttt") (8 . "eee")
         (9 . "aaa") (9 . "zzz") (9 . "ppp") (9 . "fff")]


      


      
See Sorting, for more
      functions that perform sorting. See
      documentation in Accessing
      Documentation, for a useful example of
      sort.

    

  
 

  
The seq.el library provides the following
  additional sequence manipulation macros and functions, prefixed
  with seq-. To use them, you must first load the
  seq library.


  
All functions defined in this library are free of
  side-effects; i.e., they do not modify any sequence (list,
  vector, or string) that you pass as an argument. Unless otherwise
  stated, the result is a sequence of the same type as the input.
  For those functions that take a predicate, this should be a
  function of one argument.


  
The seq.el library can be extended to work with
  additional types of sequential data-structures. For that purpose,
  all functions are defined using cl-defgeneric. See
  Generic
  Functions, for more details about using
  cl-defgeneric for adding extensions.


  

    
Function: seq-elt
    sequence index


    

      
This function returns the element of sequence
      at the specified index, which is an integer whose
      valid value range is zero to one less than the length of
      sequence. For out-of-range values on built-in
      sequence types, seq-elt behaves like
      elt. For the details, see Definition of elt.


      

        
(seq-elt [1 2 3 4] 2)
⇒ 3


      


      
seq-elt returns places settable using
      setf (see 
      Setting Generalized Variables).


      

        
(setq vec [1 2 3 4])
(setf (seq-elt vec 2) 5)
vec
⇒ [1 2 5 4]


      

    

  


  

    
Function:
    seq-length sequence


    

      
This function returns the number of elements in
      sequence. For built-in sequence types,
      seq-length behaves like length. See
      Definition of length.

    

  


  

    
Function:
    seqp sequence


    

      
This function returns non-nil if
      sequence is a sequence (a list or array), or any
      additional type of sequence defined via seq.el
      generic functions.


      

        
(seqp [1 2])
⇒ t


        
(seqp 2)
⇒ nil


      

    

  


  

    
Function: seq-drop
    sequence n


    

      
This function returns all but the first n (an
      integer) elements of sequence. If n is
      negative or zero, the result is sequence.


      

        
(seq-drop [1 2 3 4 5 6] 3)
⇒ [4 5 6]


        
(seq-drop "hello world" -4)
⇒ "hello world"


      

    

  


  

    
Function: seq-take
    sequence n


    

      
This function returns the first n (an integer)
      elements of sequence. If n is negative
      or zero, the result is nil.


      

        
(seq-take '(1 2 3 4) 3)
⇒ (1 2 3)


        
(seq-take [1 2 3 4] 0)
⇒ []


      

    

  


  

    
Function:
    seq-take-while predicate
    sequence


    

      
This function returns the members of sequence
      in order, stopping before the first one for which
      predicate returns nil.


      

        
(seq-take-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2))
⇒ (1 2 3)


        
(seq-take-while (lambda (elt) (> elt 0)) [-1 4 6])
⇒ []


      

    

  


  

    
Function:
    seq-drop-while predicate
    sequence


    

      
This function returns the members of sequence
      in order, starting from the first one for which
      predicate returns nil.


      

        
(seq-drop-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2))
⇒ (-1 -2)


        
(seq-drop-while (lambda (elt) (< elt 0)) [1 4 6])
⇒ [1 4 6]


      

    

  


  

    
Function: seq-do
    function sequence


    

      
This function applies function to each element
      of sequence in turn (presumably for side effects),
      and returns sequence.

    

  


  

    
Function: seq-map
    function sequence


    

      
This function returns the result of applying
      function to each element of sequence.
      The returned value is a list.


      

        
(seq-map #'1+ '(2 4 6))
⇒ (3 5 7)


        
(seq-map #'symbol-name [foo bar])
⇒ ("foo" "bar")


      

    

  


  

    
Function: seq-mapn
    function &rest sequences


    

      
This function returns the result of applying
      function to each element of sequences.
      The arity (see sub-arity)
      of function must match the number of sequences.
      Mapping stops at the end of the shortest sequence, and the
      returned value is a list.


      

        
(seq-mapn #'+ '(2 4 6) '(20 40 60))
⇒ (22 44 66)


        
(seq-mapn #'concat '("moskito" "bite") ["bee" "sting"])
⇒ ("moskitobee" "bitesting")


      

    

  


  

    
Function:
    seq-filter predicate sequence


    

      

      
This function returns a list of all the elements in
      sequence for which predicate returns
      non-nil.


      

        
(seq-filter (lambda (elt) (> elt 0)) [1 -1 3 -3 5])
⇒ (1 3 5)


        
(seq-filter (lambda (elt) (> elt 0)) '(-1 -3 -5))
⇒ nil


      

    

  


  

    
Function:
    seq-remove predicate sequence


    

      

      
This function returns a list of all the elements in
      sequence for which predicate returns
      nil.


      

        
(seq-remove (lambda (elt) (> elt 0)) [1 -1 3 -3 5])
⇒ (-1 -3)


        
(seq-remove (lambda (elt) (< elt 0)) '(-1 -3 -5))
⇒ nil


      

    

  


  

    
Function:
    seq-reduce function sequence
    initial-value


    

      

      
This function returns the result of calling
      function with initial-value and the
      first element of sequence, then calling
      function with that result and the second element
      of sequence, then with that result and the third
      element of sequence, etc. function
      should be a function of two arguments. If sequence
      is empty, this returns initial-value without
      calling function.


      

        
(seq-reduce #'+ [1 2 3 4] 0)
⇒ 10


        
(seq-reduce #'+ '(1 2 3 4) 5)
⇒ 15


        
(seq-reduce #'+ '() 3)
⇒ 3


      

    

  


  

    
Function: seq-some
    predicate sequence


    

      
This function returns the first non-nil value
      returned by applying predicate to each element of
      sequence in turn.


      

        
(seq-some #'numberp ["abc" 1 nil])
⇒ t


        
(seq-some #'numberp ["abc" "def"])
⇒ nil


        
(seq-some #'null ["abc" 1 nil])
⇒ t


        
(seq-some #'1+ [2 4 6])
⇒ 3


      

    

  


  

    
Function: seq-find
    predicate sequence &optional default


    

      
This function returns the first element in
      sequence for which predicate returns
      non-nil. If no element matches
      predicate, the function returns
      default.


      
Note that this function has an ambiguity if the found
      element is identical to default, as in that case
      it cannot be known whether an element was found or not.


      

        
(seq-find #'numberp ["abc" 1 nil])
⇒ 1


        
(seq-find #'numberp ["abc" "def"])
⇒ nil


      

    

  


  

    
Function:
    seq-every-p predicate sequence


    

      
This function returns non-nil if applying
      predicate to every element of sequence
      returns non-nil.


      

        
(seq-every-p #'numberp [2 4 6])
⇒ t


        
(seq-some #'numberp [2 4 "6"])
⇒ nil


      

    

  


  

    
Function:
    seq-empty-p sequence


    

      
This function returns non-nil if
      sequence is empty.


      

        
(seq-empty-p "not empty")
⇒ nil


        
(seq-empty-p "")
⇒ t


      

    

  


  

    
Function: seq-count
    predicate sequence


    

      
This function returns the number of elements in
      sequence for which predicate returns
      non-nil.


      

        
(seq-count (lambda (elt) (> elt 0)) [-1 2 0 3 -2])
⇒ 2


      

    

  


  

    
Function: seq-sort
    function sequence


    

      
This function returns a copy of sequence that
      is sorted according to function, a function of two
      arguments that returns non-nil if the first
      argument should sort before the second.

    

  


  

    
Function:
    seq-contains sequence elt &optional
    function


    

      
This function returns the first element in
      sequence that is equal to elt. If the
      optional argument function is
      non-nil, it is a function of two arguments to
      use instead of the default equal.


      

        
(seq-contains '(symbol1 symbol2) 'symbol1)
⇒ symbol1


        
(seq-contains '(symbol1 symbol2) 'symbol3)
⇒ nil


      

    

  


  

    
Function:
    seq-position sequence elt &optional
    function


    

      
This function returns the index of the first element in
      sequence that is equal to elt. If the
      optional argument function is
      non-nil, it is a function of two arguments to
      use instead of the default equal.


      

        
(seq-position '(a b c) 'b)
⇒ 1


        
(seq-position '(a b c) 'd)
⇒ nil


      

    

  


  

    
Function: seq-uniq
    sequence &optional function


    

      
This function returns a list of the elements of
      sequence with duplicates removed. If the optional
      argument function is non-nil, it is a
      function of two arguments to use instead of the default
      equal.


      

        
(seq-uniq '(1 2 2 1 3))
⇒ (1 2 3)


        
(seq-uniq '(1 2 2.0 1.0) #'=)
⇒ [3 4]


      

    

  


  

    
Function:
    seq-subseq sequence start &optional
    end


    

      
This function returns a subset of sequence from
      start to end, both integers
      (end defaults to the last element). If
      start or end is negative, it counts
      from the end of sequence.


      

        
(seq-subseq '(1 2 3 4 5) 1)
⇒ (2 3 4 5)


        
(seq-subseq '[1 2 3 4 5] 1 3)
⇒ [2 3]


        
(seq-subseq '[1 2 3 4 5] -3 -1)
⇒ [3 4]


      

    

  


  

    
Function:
    seq-concatenate type &rest
    sequences


    

      
This function returns a sequence of type type
      made of the concatenation of sequences.
      type may be: vector,
      list or string.


      

        
(seq-concatenate 'list '(1 2) '(3 4) [5 6])
⇒ (1 2 3 5 6)


        
(seq-concatenate 'string "Hello " "world")
⇒ "Hello world"


      

    

  


  

    
Function:
    seq-mapcat function sequence &optional
    type


    

      
This function returns the result of applying
      seq-concatenate to the result of applying
      function to each element of sequence.
      The result is a sequence of type type, or a list
      if type is nil.


      

        
(seq-mapcat #'seq-reverse '((3 2 1) (6 5 4)))
⇒ (1 2 3 4 5 6)


      

    

  


  

    
Function:
    seq-partition sequence n


    

      
This function returns a list of the elements of
      sequence grouped into sub-sequences of length
      n. The last sequence may contain less elements
      than n. n must be an integer. If
      n is a negative integer or 0, the return value is
      nil.


      

        
(seq-partition '(0 1 2 3 4 5 6 7) 3)
⇒ ((0 1 2) (3 4 5) (6 7))


      

    

  


  

    
Function:
    seq-intersection sequence1 sequence2
    &optional function


    

      
This function returns a list of the elements that appear
      both in sequence1 and sequence2. If the
      optional argument function is
      non-nil, it is a function of two arguments to
      use to compare elements instead of the default
      equal.


      

        
(seq-intersection [2 3 4 5] [1 3 5 6 7])
⇒ (3 5)


      

    

  


  

    
Function:
    seq-difference sequence1 sequence2
    &optional function


    

      
This function returns a list of the elements that appear
      in sequence1 but not in sequence2. If
      the optional argument function is
      non-nil, it is a function of two arguments to
      use to compare elements instead of the default
      equal.


      

        
(seq-difference '(2 3 4 5) [1 3 5 6 7])
⇒ (2 4)


      

    

  


  

    
Function:
    seq-group-by function sequence


    

      
This function separates the elements of
      sequence into an alist whose keys are the result
      of applying function to each element of
      sequence. Keys are compared using
      equal.


      

        
(seq-group-by #'integerp '(1 2.1 3 2 3.2))
⇒ ((t 1 3 2) (nil 2.1 3.2))


        
(seq-group-by #'car '((a 1) (b 2) (a 3) (c 4)))
⇒ ((b (b 2)) (a (a 1) (a 3)) (c (c 4)))


      

    

  


  

    
Function: seq-into
    sequence type


    

      
This function converts the sequence sequence
      into a sequence of type type. type can
      be one of the following symbols: vector,
      string or list.


      

        
(seq-into [1 2 3] 'list)
⇒ (1 2 3)


        
(seq-into nil 'vector)
⇒ []


        
(seq-into "hello" 'vector)
⇒ [104 101 108 108 111]


      

    

  


  

    
Function: seq-min
    sequence


    

      
This function returns the smallest element of
      sequence. The elements of sequence must
      be numbers or markers (see Markers).


      

        
(seq-min [3 1 2])
⇒ 1


        
(seq-min "Hello")
⇒ 72


      

    

  


  

    
Function: seq-max
    sequence


    

      
This function returns the largest element of
      sequence. The elements of sequence must
      be numbers or markers.


      

        
(seq-max [1 3 2])
⇒ 3


        
(seq-max "Hello")
⇒ 111


      

    

  


  

    
Macro: seq-doseq
    (var sequence) body…


    

      

      
This macro is like dolist (see dolist), except that
      sequence can be a list, vector or string. This is
      primarily useful for side-effects.

    

  


  

    
Macro: seq-let
    arguments sequence body…


    

      

      
This macro binds the variables defined in
      arguments to the elements of sequence.
      arguments can themselves include sequences,
      allowing for nested destructuring.


      
The arguments sequence can also include the
      &rest marker followed by a variable name to
      be bound to the rest of sequence.


      

        
(seq-let [first second] [1 2 3 4]
  (list first second))
⇒ (1 2)


        
(seq-let (_ a _ b) '(1 2 3 4)
  (list a b))
⇒ (2 4)


        
(seq-let [a [b [c]]] [1 [2 [3]]]
  (list a b c))
⇒ (1 2 3)


        
(seq-let [a b &rest others] [1 2 3 4]
  others)


        
⇒ [3 4]


      

    

  

  


  

    
Next: , Up: Sequences Arrays Vectors  
    [Contents][Index]